概述

Resolves #90

本次实现了Tool Script Safety Guard，用于在 Tool / Skill / MCP Tool /
CodeExecutor 执行脚本或命令前进行安全扫描、策略判断、拦截和审计。

主要能力：

• 支持 Python 脚本和 Bash 命令的静态安全扫描
• 支持 allow / deny / needs_human_review 三类决策
• 支持 YAML 策略配置：白名单域名、允许命令、禁止路径、最大超时、最大输出大小
• 支持 strict policy validation，能发现未知字段、错误类型和负数限制值
• 输出结构化安全报告，包含 decision、risk_level、rule_id、evidence、
  recommendation
• 输出 JSONL 审计事件，便于监控系统消费
• 预留 OpenTelemetry 兼容的 tool.safety.* attributes
• 提供 CLI、Filter、Wrapper、示例和自动化测试
• 为 BashTool 和 UnsafeLocalCodeExecutor 提供 opt-in 接入，不改变默认历史
  行为
• 提供 40 条 manifest 驱动样例，覆盖 issue 要求的主要风险类型和常见绕过场景

风险覆盖

已覆盖的风险类型：

• 危险文件操作：递归删除、系统路径覆盖、.env、~/.ssh、凭据文件访问等
• 网络外连：curl、wget、requests、aiohttp、socket、非白名单域名访问
  等
• 进程和系统命令：subprocess、os.system、shell 管道、命令替换、后台进程、
  提权命令等
• 依赖安装：pip install、python -m pip install、npm install、apt install 等
• 资源滥用：无限循环、fork bomb、长时间 sleep、超时和输出大小策略检查等
• 敏感信息泄漏：API key、token、password、私钥内容输出或传输等

额外补充的高价值场景：

• base64 | sh
• python -c
• bash -c / sh -c
• 动态 URL 拼接
• 动态 .env / ~/.ssh 路径
• curl --data-binary @.env
• find -delete
• xargs rm -rf
• os.getenv("API_TOKEN") 外传

兼容性

核心执行链路接入采用 opt-in 方式，避免破坏现有默认行为。

BashTool 和 UnsafeLocalCodeExecutor 默认保持原有执行逻辑。用户可以通过参数
enable_safety_guard=True 显式启用安全扫描。

启用后：

• deny 会在执行前阻断脚本或命令
• needs_human_review 默认只记录到 safety_report、audit 和 telemetry，不阻
  断执行
• 如需严格模式，可设置 block_on_review=True
• allow 会继续执行

验收映射

• Python 和 Bash 扫描：trpc_agent_sdk/tools/safety/_rules.py、_scanner.py
• 可配置 YAML policy：trpc_agent_sdk/tools/safety/_policy.py、examples/ tool_safety/tool_safety_policy.yaml
• strict policy validation：未知字段、错误类型、负数限制值会报错
• 三态决策模型：allow、deny、needs_human_review
• Filter / Wrapper 执行前拦截：trpc_agent_sdk/tools/safety/_filter.py、
  _wrapper.py
• 核心链路 opt-in 接入：trpc_agent_sdk/tools/file_tools/_bash_tool.py、
  trpc_agent_sdk/code_executors/local/_unsafe_local_code_executor.py
• 结构化报告字段：decision、risk_level、rule_id、risk_type、
  evidence、recommendation
• 审计和遥测：trpc_agent_sdk/tools/safety/_audit.py、_telemetry.py
• CLI：scripts/tool_safety_check.py
• Manifest 验收脚本：scripts/tool_safety_manifest_report.py
• 样例与报告：examples/tool_safety/samples/manifest.yaml、examples/ tool_safety/all_reports.json
• 文档：examples/tool_safety/README.md

样例校验

样例语料由 manifest 驱动：

• Manifest：examples/tool_safety/samples/manifest.yaml
• Deterministic report：examples/tool_safety/all_reports.json
• 校验脚本：scripts/tool_safety_manifest_report.py

当前 manifest 状态：

• 40 个样例
• 40 / 40 expected decision 匹配
• 40 / 40 required rule ids 匹配
• 读取密钥样例：无 allow
• 危险删除样例：无 allow
• 非白名单网络外连样例：无 allow
• 安全样例：无 deny
• 500 行 Python 脚本扫描性能由测试覆盖

验证

已通过相关测试和校验：

.venv/bin/python -m pytest tests/tools/safety -q
.venv/bin/python scripts/tool_safety_manifest_report.py --strict-policy
.venv/bin/python -m flake8 trpc_agent_sdk/tools/safety scripts/tool_safety_check.py scripts/tool_safety_manifest_report.py tests/tools/safety
.venv/bin/python -m yapf --diff --recursive trpc_agent_sdk/tools/safety scripts/tool_safety_check.py scripts/tool_safety_manifest_report.py tests/tools/safety

当前结果：

• tests/tools/safety：82 passed
• Manifest 样例：40 / 40 expected decision 匹配
• Required rule ids：40 / 40 匹配
• flake8 通过
• yapf --diff 无格式 diff
• 已补充 Codecov 提示的 _policy.py 和 _rules.py patch coverage 缺失分支测试

也验证了单文件 CLI 扫描：

.venv/bin/python scripts/tool_safety_check.py \
  --script examples/tool_safety/samples/danger_delete.sh \
  --language bash \
  --policy examples/tool_safety/tool_safety_policy.yaml \
  --strict-policy

结果：deny，命中 BASH_RECURSIVE_DELETE。

文档

新增 examples/tool_safety/README.md，说明：

• 规则体系
• 策略配置
• CLI 使用方式
• Filter / Wrapper 接入方式
• BashTool / UnsafeLocalCodeExecutor opt-in 接入方式
• 报告和审计日志格式
• OpenTelemetry 字段
• 已知误报、漏报和绕过风险
• 为什么静态扫描不能替代沙箱隔离